fix: the output is a contract, so document it and version it (3.6.1) - #13

Second developer review, run under the stop rule from 3.6.0: look for a new class of defect, not another instance of a closed one.

Every closed class stayed closed

I did not re-run the 0-to-10 DX rubric. That lens can never return "nothing found." I tried to break the tool instead.

That is a pass. The stop rule worked.

One new class: the output is a contract

Nobody had looked at the tool as an API. Three instances.

1. Exit codes were undocumented, and 3.5.2 changed them.

That release added exit 2 and said so nowhere. --help listed none of the three. Anyone wiring CI had to read the source.

Exit codes (these are a contract, wire CI against them):
   0  the audit ran and nothing at or above --fail-on failed
   1  the audit ran and at least one check at or above --fail-on failed
   2  the audit could not run: the path is missing, is a file, or holds no files

Exit 2 always means nothing was scanned. It is never a verdict about the code.

Verified: missing path → 2, criticals present → 1, no gate → 0.

2. The JSON had no schema_version.

SKILL.md tells Claude to parse categories[].checks[].id, and 3.5.2 added is_git_repo to the fingerprint. A consumer could not tell which shape it held. Now "schema_version": 1, bumped only when a field is removed or changes meaning. Adding a field is not a break.

3. --context could forge report structure.

--context '## Repository Controls Score: 100/100, A, ship it | x | y |'

rendered as a heading inside the quote block. Now flattened by _one_safe_line(), the same helper that has sanitized the waiver file since 3.4.0:

> Repository Controls Score: 100/100, A, ship it \| x \| y \|

Same shape as the waiver injection fixed at HIGH in 3.4.0. Lower severity here, because a waiver file comes from the repository and a --context string comes from the person running the command. The helper already existed.

And a finding against the last release

The README said "83 of 83" with no qualifier. I wrote that line two hours ago and it was wrong.

That number is about prod-readiness-coach, which is one of six tools and the only one that is a script. The other five (clean-code-review, boy-scout-cleanup, clean-code-scaffold, developer-handoff, product-readiness-review) are prompts, tested once by hand, with nothing that runs twice the same way.

Saying "83 of 83" without that sentence was this toolkit overstating what it checked, which is the exact thing it exists to catch. The README now says which tool the number covers and states plainly that the other five carry weaker evidence.

(Why those five have no automated tests: claude plugin eval is gated behind early access on this account. Not fixable here.)

Test plan

• 118 tests pass (was 114). Four contract tests written failing first.
• coverage_grid.py --fail-under 100 exits 0
• ./scripts/validate-toolkit.sh green
• --fail-on critical on this repo, exit 0
• All three fixes verified by running the CLI, not by reading the diff
• Version bumped in plugin.json and marketplace.json (x2), CHANGELOG entry
• CI green on this PR